Skip to content
This repository has been archived by the owner on Jun 22, 2024. It is now read-only.

Add initial IBM Cloud Functions examples #20

Open
wants to merge 30 commits into
base: main
Choose a base branch
from

Conversation

mrutkows
Copy link

@mrutkows mrutkows commented Jul 16, 2020

First drop of of NodeJS examples for IBM Cloud Functions (ICF) with background info. seeking to address issue #15.

Please feel free to assign the issue to me, as well as this PR.

@mhdawson
Copy link
Member

@mrutkows thanks. Will try to review next week.

@mrutkows
Copy link
Author

@mrutkows thanks. Will try to review next week.

Thanks @mhdawson, this is a WIP (draft) at the moment and hope to complete shortly...

@mhdawson
Copy link
Member

@mrutkows thanks for the update, let me know once its complete, I'll hold of reviewing until then.

@mrutkows mrutkows marked this pull request as ready for review July 29, 2020 14:06
@mrutkows
Copy link
Author

mrutkows commented Jul 29, 2020

@mhdawson After some delay to track down an issue... I believe it is now ready for a review. Please note that I updated the top-level README to alphabetize the listed technpologies and move gcr to what I believe is the correct category.

# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part of the licence does not seem quite right.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unless the README.md is a copy from somewhere else ?


### ZIP action

The NodeJS runtime, where your function executes, has a [fixed list of installed NPM modules](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-runtimes#openwhisk_ref_javascript_environments). If you require more NPM modules, you can ZIP them with your action code.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what I understand later is that you zip up some files, but that does not necessarily include the npm modules themselves but instead a package.json file that list the dependencies. I think the current wording might confuse people into thinking the zip will include the npm modules.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nevermind reading again I see the npm modules are zipped up.

* [Hello HTML](#hello-html) - *create HTML content*
* [Using query parameters](#using-query-parameters)
* [Atomic SVG](#atomic-svg) - *create SVG content*
* [Sequencing actions](sequences.md#sequencing-actions) - *easily create sequences of existing actions*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems a bit strange that all of the sections except this one are in the doc if you read through it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems a bit strange that all of the sections except this one are in the doc if you read through it.

Yeah, Sequences are bordering on an intermediate topic... had hoped to eventually make sequences.md into a second chapter dedicated to higher order examples. Plus I had it already as a separate file and wanted to add it at the last minute at the end of the day I had reserved to complete these.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mhdawson FYI, found time at the end of last week to move the content from sequences.md to README.md ... latest commit reflects this.


If you like using ICF, you can sign-up for the *free*, self-study [Cognitve Class.ai](https://cognitiveclass.ai/) course and get [Acclaim badge](https://www.youracclaim.com/org/ibm/badge/serverless-computing-using-cloud-functions-developer-i) certified:
* [Serverless Computing using Cloud Functions - Developer I course](https://cognitiveclass.ai/courses/serverless-computing-using-cloud-functions-developer-1)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it also make sense to add a reference to the full docs here as well ?

Copy link
Author

@mrutkows mrutkows Jul 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it also make sense to add a reference to the full docs here as well ?

If I find time, I would love to do a follow-on PR that sets up the readme to introduce a few more advanced topic examples and can add more canonical links (including granular ones for each use case where possible).

Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM once the licence is fixed up and also made a few suggestions.

@mrutkows
Copy link
Author

mrutkows commented Jul 30, 2020

@mhdawson Thanks for the find... changed the license headers to vanilla Apache 2 boilerplate for the two markdown files.

cloud/serverless/ibm-cloud-functions/README.md Outdated Show resolved Hide resolved
cloud/serverless/ibm-cloud-functions/README.md Outdated Show resolved Hide resolved
cloud/serverless/ibm-cloud-functions/README.md Outdated Show resolved Hide resolved
cloud/serverless/ibm-cloud-functions/README.md Outdated Show resolved Hide resolved
7. Invoke the action with parameters (block for `-r` result):

```bash
ic fn action invoke namegen -p race human -p gender female -r
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ic fn action invoke namegen -p race human -p gender female -r
ibmcloud fn action invoke namegen -p race human -p gender female -r

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rodion-arr Thanks for finding the last CLI command alias ;)

@bnb bnb changed the base branch from master to main August 7, 2020 19:02
@bnb
Copy link
Contributor

bnb commented Aug 7, 2020

Retargeted to main, will check this as soon as I can - have been slammed with some other priorities recently ❤️

Copy link
Contributor

@bnb bnb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've gone through and provided edits to this PR as it stands for completeness, though I don't think it can land how it currently exists.

The intent of this repository is to provide git clone-able full code examples of projects that use Node.js. This is a strong and comprehensive tutorial, but that specific content is outside of the scope of the nodejs/examples repository.

Ideally, I'd really love to see the various examples provided within moved into directories that follow a similar structure to cli/yargs/countEntriesInDirectory where I could git clone and then deploy it with the prose parts of each section in the README of the directory where the code exists as it would be if it were "final" and prod ready. Additionally, going above and beyond, having the deployment commands as npm scripts would be super awesome.

Ideally, this request won't be a ton of additional work - you've got a bunch of examples here, they just need to be effectively built out as actual projects and committed as such in addition to refactoring them out of the README once they've been projectized.

cloud/README.md Outdated
- Cloud-specific (AWS, GCP, Azure, IBM Cloud, DigitalOcean, Alibaba Cloud, Oracle Cloud)
- Tiny Clouds (Netlify, Now, Glitch, CloudFlare Workers, Heroku, Surge, Begin)
- Containers (Docker, Google Cloud Run)
- Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feedback:

  • Google Cloud Run is built on top of Knative, which is "serverless". I'd prefer to leave Google Cloud Run here rather than in containers. Containers are an implementation detail of them rather than the whole thing.
  • Please restore the original order of Serverless Framework and OpenFaaS being first.
  • I'd prefer to not link directly to specific example sections since this is supposed to be a list of examples rather than what we've got.
  • Please remove "MS" - Azure Functions is the name of the platform. There are zero places where anything by Microsoft is prefixed by "MS".

Copy link
Author

@mrutkows mrutkows Aug 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feedback:

* Google Cloud Run is built on top of Knative, which is "serverless". I'd prefer to leave Google Cloud Run here rather than in containers. Containers are an implementation detail of them rather than the whole thing.

Will revert GCR back; made this change since it is not billed as a Serverless solution/platform despite using Knative underneath (from GCR product page: "Fully managed compute platform for deploying and scaling containerized applications quickly and securely.") and there is only one mention of serverless on

* Please restore the original order of Serverless Framework and OpenFaaS being first.

Alphabetical by service/project provider (company) seems to be the most fair way to list; is there a reason to give preference to these 2 solutions?

* I'd prefer to not link directly to specific example sections since this is supposed to be a list of examples rather 

Being the first to submit content, had no guidance and assumed "links" are good and that this "cloud" readme would shape up to an index into the specific examples. Will remove.

  • Please remove "MS" - Azure Functions is the name of the platform. There are zero places where anything by Microsoft is prefixed by "MS".

Did this simply to preserve the alphabetical (fairness). From Azure one can infer MS of course...

cloud/README.md Outdated
- Containers (Docker, Google Cloud Run)
- Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework)
- Orchestration (Kubernetes, OpenShift, Terraform)
- Cloud-specific (Alibaba Cloud, AWS, DigitalOcean, GCP, IBM Cloud, MS Azure, Oracle Cloud)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove "MS" 👍🏻

cloud/README.md Outdated
- Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework)
- Orchestration (Kubernetes, OpenShift, Terraform)
- Cloud-specific (Alibaba Cloud, AWS, DigitalOcean, GCP, IBM Cloud, MS Azure, Oracle Cloud)
- Edge / Tiny Clouds (Begin, CloudFlare Workers, Glitch, Heroku, Netlify, Now, Surge)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to do Edge, I'd say that should be a different line item since AFAIK each of the major clouds also all have their own Edge Compute services.

I would classify CloudFlare Workers within the category it's been added to here, but Edge is a loaded term that I think in the context of Cloud has a much more common term.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to do Edge, I'd say that should be a different line item since AFAIK each of the major clouds also all have their own Edge Compute services.

I would classify CloudFlare Workers within the category it's been added to here, but Edge is a loaded term that I think in the context of Cloud has a much more common term.

Please know that I did not add these entries (they existed already) and I did it since whenever we talk about the future of Serverless Edge computing is a primary direction and CloudFlare is the prime example always referenced.

Comment on lines 1 to 22
<!--
#
# Copyright [2020] [IBM Corporation]
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->

<!--
# Contributors:
# - Matt Rutkowski, IBM
-->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code in this repository is already licensed as MIT. I'd prefer to not dual-license or sub-license files within the repository.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code in this repository is already licensed as MIT. I'd prefer to not dual-license or sub-license files within the repository.

The majority of this content is copied from a public repo. licensed under Apache 2.


# IBM Cloud Functions using Node.js

These examples will show you how to take Node.js functions and deploy and run them within the IBM Cloud Functions (ICF) Serverless platform. Further examples will show you how to take advantage of some of ICF's built-in features to easily realize the true power of Serverless against some of its top use cases.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Serverless platform. Further

Please use single spaces after periods.

Comment on lines +597 to +607
```bash
ibmcloud fn action create split funcs.js --main split
```

```bash
ibmcloud fn action create reverse funcs.js --main reverse
```

```bash
ibmcloud fn action create join funcs.js --main join
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

Comment on lines 613 to 662
The function `split` takes the single string `hello world` and splits it into a JSON map of the individual `strings` using the space character as the delimiter.

```bash
ibmcloud fn action invoke split --result --param text "Hello world"
```

<details>
<summary>Sample output:</summary>
```json
{
"words": [
"Hello",
"world"
]
}
```
</details>

The function `reverse` takes a JSON array of `strings` and reverses the characters in each.

```bash
ibmcloud fn action invoke reverse --result --param words '["hello", "world"]'
```

<details>
<summary>Sample output:</summary>
```json
{
"words": [
"olleh",
"dlrow"
]
}
```
</details>

The function `join` takes the JSON array of `strings` and concatenates them back into a space-delimited string.

```bash
ibmcloud fn action invoke join --result --param words '["hello", "world"]'
```

<details>
<summary>Sample output:</summary>
```json
{
"text": "hello world"
}
```
</details>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

Copy link
Author

@mrutkows mrutkows Aug 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

I need this to preserve code snippets and paragraphs to be included under the numbered bullets as intended.

Comment on lines +666 to +668
```bash
ibmcloud fn action create reverse_words --sequence split,reverse,join
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

I need this to preserve code snippets to be included under the numbered bullets as intended.

Comment on lines +672 to +680
```bash
ibmcloud fn action invoke reverse_words --result --param text "hello world"
```

```json
{
"text": "olleh dlrow"
}
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the four-space indent.

I need this to preserve code snippets to be included under the numbered bullets as intended.

- By convention, the `main` function is called. You can always alias "main" to any function in your `.js` file.
- **No build step**. Runtimes for all supported languages are already deployed in ICF server clusters waiting for your function to be deployed and invoked.
- **Node.js runtime inferred**. The Node.js runtime was inferred via the function's `.js` extension. ICF will always use the latest supported Node.js runtime version unless you explicitly set another version with the `--kind` flag.
- **Package dependencies as ZIP files**. Complex actions can be constructed by packaging required NPM modules within a ZIP file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NPM should be npm

@mrutkows
Copy link
Author

mrutkows commented Aug 11, 2020

@bnb I need (irony)

inline html (only) to allow for large output to be hidden unless the developer cares to compare their output to a sample. Otherwise, we want to hide it (as a dropdown) to not clutter the actual CLI commands and make the README appear overly long and complicated.

@mrutkows
Copy link
Author

@bnb if we can update the linter to allow

so the README looks clean and if I add subdirs. (1 per each unique example (.js, and .json if applicable) is that enough?

@mrutkows
Copy link
Author

Functional .js snippets and supporting .json now in separate subdirs (1 per unique example).

@mrutkows mrutkows requested a review from bnb August 12, 2020 19:44
@mrutkows
Copy link
Author

@bnb @mhdawson Passes new linter; addressed examples layout. Please review when able.

@mhdawson
Copy link
Member

One question about path for one file, otherwise looks good to me and I think you've addressed what @bnb was looking for in terms of changes. @bnb what do you think?

@mrutkows
Copy link
Author

mrutkows commented Aug 13, 2020

Please note that the README instructs still asks the developer to create the functional files wherever they happen to be in their terminal...

If the expectation (not clear to me) is that the developer would clone this entire repo., then one could provide directory relative instructions, but had assumed developers would "pick and choose" which tech/examples they would try and not require them to clone the entire repo. which could get quite large given the scope being planned

@mrutkows
Copy link
Author

One question about path for one file, otherwise looks good to me and I think you've addressed what @bnb was looking for in terms of changes. @bnb what do you think?

drag/drop error in vscode... good catch (fixed)

@joesepi
Copy link
Member

joesepi commented Sep 16, 2020

@bnb when you get a moment, let's discuss this. If there is anything else needed, I can do so, otherwise, it should be good to go? Thanks!!! ❤️

@bnb
Copy link
Contributor

bnb commented Sep 16, 2020

@joesepi was planning on taking a look next week when I'm back from OOO 👍🏻

Comment on lines +1 to +14
<!--
Copyright 2020 IBM Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-->

<!--
# Contributors:
# - Matt Rutkowski, IBM
-->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This license header shouldn't be here since the code is in an open-source repo in the Node.js GitHub organization that's already permissibly licensed.

@bnb
Copy link
Contributor

bnb commented Sep 25, 2020

@joesepi it looks like a lot of the feedback I've given previously in the PR (specifically in the README) hasn't been addressed 😬

So, being totally upfront: the content in the README is really good and too comprehensive/tutorial-esque for this repository.

My recommendation here would be to strip out the README here and put it into an article that we publish once this PR is merged and replace the current README that's more along the lines of a typical OSS project REAMDE that you'd expect to see on GitHub / npm. This is an example specific to IBM Cloud Functions, and here are a few generic examples of the style I'm talking about.

More than happy to help how I can on this - pairing, advice, etc.

@joesepi
Copy link
Member

joesepi commented Sep 25, 2020

Okay. That makes sense. I'll look at this as soon as I can and help get it over the finish line. I like the idea of a blog post too.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants